IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / Vk / VkMenu.z / VkMenu

Wrap

Text File | 2002-10-03 | 31.0 KB | 859 lines

VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) NNNNAAAAMMMMEEEE VkMenu - Abstract base class for all ViewKit menu container objects IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM VkMenuItem : VkComponent : VkCallbackObject HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE #include <Vk/VkMenu.h> PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY AAAAddddddddiiiinnnngggg IIIItttteeeemmmmssss VkMenuAction *addAction(const char *name, XtCallbackProc func, XtPointer data, int pos = -1); VkMenuAction *addAction(const char *name, XtCallbackProc func, XtCallbackProc undoCallabck, XtPointer data, int pos = -1); VkMenuActionWidget *addActionWidget(const char *name, XtCallbackProc func, XtPointer data, int pos = -1); VkMenuActionWidget *addActionWidget(const char *name, XtCallbackProc func, XtCallbackProc undoCallback, XtPointer data, int pos = -1); VkMenuConfirmFirstAction *addConfirmFirstAction(const char *name, XtCallbackProc func, XtPointer data, int pos = -1); VkMenuSeparator *addSeparator(int pos = -1); VkMenuLabel *addLabel(const char *name, int pos = -1); VkMenuToggle *addToggle(const char *name, XtCallbackProc func, XtPointer data, int state = -1, int pos = -1); VkMenuToggle *addToggle(const char *name, XtCallbackProc func, XtCallbackProc undoCallback, PPPPaaaaggggeeee 1111 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) XtPointer data, int state = -1, int pos = -1); void add(VkMenuItem *name, int pos = -1); VkSubMenu *addSubmenu(VkSubMenu *submenu, int pos = -1); VkSubMenu *addSubmenu(const char *name, int pos = -1); VkSubMenu *addSubmenu(const char *name, VkMenuDesc *desc, XtPointer defaultClientData = NULL); VkRadioSubMenu *addRadioSubmenu(VkRadioSubMenu *submenu, int pos = -1); VkRadioSubMenu *addRadioSubmenu(const char *name, int pos = -1); VkRadioSubMenu *addRadioSubmenu(const char *name, VkMenuDesc *desc, XtPointer defaultClientData = NULL); MMMMaaaannnniiiippppuuuullllaaaattttiiiinnnngggg IIIItttteeeemmmmssss VkMenuItem *findNamedItem(const char *name, Boolean caseless = FALSE); VkMenuItem *removeItem(const char *name); VkMenuItem *activateItem(const char *name ); VkMenuItem *deactivateItem(const char *name ); VkMenuItem *replace(const char *name , VkMenuItem *item ); AAAAcccccccceeeessssssss FFFFuuuunnnnccccttttiiiioooonnnnssss virtual VkMenuItemType menuType () = 0; virtual const char* className(); Boolean isContainer(); int getItemPosition(VkMenuItem* item); int getItemPosition(char *name); int getItemPosition(Widget); VkMenuItem * operator[] (int index) const; int numItems() const; AAAAcccccccceeeessssssss FFFFuuuunnnnccccttttiiiioooonnnnssss ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy VkScreen *getScreen(); CCCCoooonnnnttttrrrroooollll FFFFuuuunnnnccccttttiiiioooonnnnssss PPPPaaaaggggeeee 2222 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) static void useOverlayMenus(const Boolean flag); static void useWorkProcs(Boolean flag); CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN VkMenu is an abstract base class that implements the bulk of the functionality needed for all menus, including menubars (see VkMenuBar(3X)), pulldowns, (see VkSubMenu(3x)), option menus (see VkOptionMenu(3X)), and popup menus (see (VkPopupMenu(3X)). Menus can be built by passing a static description to the constructor of a class derived from VkMenu or by adding items dynamically. The two approaches can be mixed; an initial menu structure can be defined statically, and then additional items can be added dynamically as needed. UUUUssssiiiinnnngggg SSSSttttaaaattttiiiicccc MMMMeeeennnnuuuu DDDDeeeessssccccrrrriiiippppttttiiiioooonnnnssss Menus can be described statically using an array of structures of type VkMenuDesc. This structure is defined as follows: struct VkMenuDesc { VkMenuItemType menuType; char *name; XtCallbackProc callback; VkMenuDesc *submenu; XtPointer clientData; XtCallbackProc undoCallback; }; Menu hierarchies can be defined by creating connected arrays of this structure. The first member of this structure indicates a menu type using the enumerated VkMenuItemType defined in VkMenuItem.h. The possible values are: AAAACCCCTTTTIIIIOOOONNNN A "normal" menu item, implemented as a VkMenuAction object CCCCOOOONNNNFFFFIIIIRRRRMMMMFFFFIIIIRRRRSSSSTTTTAAAACCCCTTTTIIIIOOOONNNN An action that will not be executed without user confirmation. AAAACCCCTTTTIIIIOOOONNNNWWWWIIIIDDDDGGGGEEEETTTT A "normal" menu item, implemented as a VkMenuActionWidget object. (This class uses a widget instead of a gadget.) SSSSUUUUBBBBMMMMEEEENNNNUUUU A cascading submenu, implemented as a VkSubMenu object RRRRAAAADDDDIIIIOOOOSSSSUUUUBBBBMMMMEEEENNNNUUUU Same as above, but forced to act as a radio-style pane, implemented as a VkRadioSubMenu object. PPPPaaaaggggeeee 3333 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) SSSSEEEEPPPPAAAARRRRAAAATTTTOOOORRRR A separator, implemented as an VkMenuSeparator object LLLLAAAABBBBEEEELLLL A label, implemented as a VkMenuLabel object TTTTOOOOGGGGGGGGLLLLEEEE A two-state toggle button gadget, implemented as a VkMenuToggle object OOOOPPPPTTTTIIIIOOOONNNN A multi-choice option menu, implemented as a VkOptionMenu object. This option would rarely be used in a menu description. PPPPOOOOPPPPUUUUPPPP A popup menu pane, implemented as a VkPopupMenu object.This option would rarely be used in a menu description. BBBBAAAARRRR A menu bar, implemented as a VkPopupMenu object.This option would rarely be used in a menu description. EEEENNNNDDDD All menu descriptions must be terminated by this constant. For example, assume you want to create a menu that contains two submenus, each of which contain two selectable actions. This menu could be described as follows: VkMenuDesc applicationPane[] = { { ACTION, "itemOne", oneCallback}, { ACTION, "itemTwo", twoCallback}, { END}, }; VkMenuDesc editPane[] = { { ACTION, "cut", cutCallback}, { ACTION, "paste", pasteCallback}, { END}, }; VkMenuDesc menu[] = { { SUBMENU, "Application", NULL, applicationPane}, { SUBMENU, "Edit", NULL, editPane}, { END} }; PPPPaaaaggggeeee 4444 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) All the various objects needed to implement this menu hierarchy could then be create as follows: VkMenuBar *menubar = VkMenuBar(menu); UUUUssssiiiinnnngggg SSSSttttaaaattttiiiicccc DDDDeeeessssccccrrrriiiippppttttiiiioooonnnnssss WWWWiiiitttthhhh VVVVkkkkWWWWiiiinnnnddddoooowwww When using static descriptions with classes derived from VkWindow, it is recommended that both callbacks and menu structures be declared as members of the class. For example, the following class creates a menubar that matches the menu hierarchy described above. class Sample: public VkWindow { private: static void oneCallback( Widget, XtPointer, XtPointer); static void twoCallback( Widget, XtPointer , XtPointer); static void cutCallback( Widget, XtPointer, XtPointer); static void pasteCallback( Widget, XtPointer , XtPointer); static VkMenuDesc applicationPane[]; static VkMenuDesc editPane[]; static VkMenuDesc menu[]; protected: public: Sample( const char *name) : VkWindow( name) // Other members }; The constructor of this class can install this menu in several ways. This example installs the menu bar using the complete description: SampleWindow::SampleWindow(char *name) : VkWindow(name) { setMenuBar(menu); PPPPaaaaggggeeee 5555 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) // Other actions } This example instantiates a menu bar and installs the object: SampleWindow::SampleWindow(char *name) : VkWindow(name) { setMenuBar(new VkMenuBar(menu, (XtPointer) this)); // Other actions } Note that the top level description in this case is not strictly required. A menubar could be added to a VkWindow subclass by adding each pane individually. For example: SampleWindow::SampleWindow(char *name) : VkWindow(name) { addMenuPane("Application", application); addMenuPane("Edit", edit); // Other actions } Although the above example shows a menu bar, the same description could be used to create other types of menus. For example, the following code segment creates a popup menu in addition to a menu bar, using the same description: SampleWindow::SampleWindow(char *name) : VkWindow(name) { // Create the menu bar addMenuPane("Application", application); addMenuPane("Edit", edit); // Create a popup that has the same // contents as the menubar VkPopupMenu *popup = new VkPopupMenu(menu); // Other actions } PPPPaaaaggggeeee 6666 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) CCCCrrrreeeeaaaattttiiiinnnngggg MMMMeeeennnnuuuussss DDDDyyyynnnnaaaammmmiiiiccccaaaallllllllyyyy Regardless of the menu type, items can be added dynamically using the protocol defined by VkMenu. For example, the menu bar constructed statically above can be created dynamically with the following code segment: VkMenuBar *menuBar = new VkMenuBar(); VkSubMenu *application = menuBar->addSubMenu("Application"); VkSubMenu *edit = menuBar->addSubMenu("Edit"); application->addAction("itemOne", oneCallback); application->addAction("itemTwo", twoCallback); edit->addAction("cut", cutCallback); edit->addAction("paste", pasteCallback); DDDDeeeerrrriiiivvvviiiinnnngggg SSSSuuuubbbbccccllllaaaasssssssseeeessss Specific types of menus are implemented as derived classes of VkMenu. These include VkOptionMenu, VkPopupMenu, VkMenuBar, VkSubMenu, and VkRadioSubMenu. The VkMenu class is not necessarily designed to support other derivations. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS aaaaddddddddAAAAccccttttiiiioooonnnn VkMenuAction *addAction(const char *name, XtCallbackProc func, XtPointer data, int pos = -1); VkMenuAction *addAction(const char *name, XtCallbackProc func, XtCallbackProc undoCallabck, XtPointer data, int pos = -1); Creates and adds an action object to a menu. The first argument indicates the name, the second specifies a callback function. The final two arguments can be used to specify some client data for the callback, and a position within the menu for this item. In the second form of this function, it is possible to add a callback to be called if the menu action is to be undone. If the first form of this function is used, the action cannot be undone and does not participate in the undo mechanism. (See VkMenuUndoManager(3X)). aaaaddddddddAAAAccccttttiiiioooonnnnWWWWiiiiddddggggeeeetttt PPPPaaaaggggeeee 7777 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VkMenuActionWidget *addActionWidget(const char *name, XtCallbackProc func, XtPointer data, int pos = -1); VkMenuActionWidget *addActionWidget(const char *name, XtCallbackProc func, XtCallbackProc undoCallback, XtPointer data, int pos = -1); Functionally equivalent to _a_d_d_A_c_t_i_o_n(), but forces the menu system to create a widget, as opposed to a gadget. Gadgets are used by default. aaaaddddddddCCCCoooonnnnffffiiiirrrrmmmmFFFFiiiirrrrssssttttAAAAccccttttiiiioooonnnn VkMenuConfirmFirstAction *addConfirmFirstAction(const char *, XtCallbackProc func, XtPointer data, int pos = -1); Some actions are potentially dangerous and/or cannot be reversed. Quitting an application might be one example. The function _a_d_d_C_o_n_f_i_r_m_F_i_r_s_t_A_c_t_i_o_n() adds an action to a menu that automatically posts a confirming dialog before executing the command. Otherwise, the function is equivalent to _a_d_d_A_c_t_i_o_n() without the option of an undo callback. aaaaddddddddSSSSeeeeppppaaaarrrraaaattttoooorrrr VkMenuSeparator *addSeparator(int pos = -1); Adds a separator item to a menu. aaaaddddddddLLLLaaaabbbbeeeellll VkMenuLabel *addLabel(const char *, int pos = -1); Add a non-selectable label item to a menu. aaaaddddddddTTTToooogggggggglllleeee VkMenuToggle *addToggle(const char *, XtCallbackProc func, XtPointer data, int state = -1, int pos = -1); VkMenuToggle *addToggle(const char *, XtCallbackProc func, XtCallbackProc undoCallback, PPPPaaaaggggeeee 8888 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) XtPointer data, int state = -1, int pos = -1); Adds a toggle item to a menu. All arguments serve the same purpose as those in _a_d_d_A_c_t_i_o_n(). An additional, optional argument, state, allows the initial state of the item to be specified. aaaadddddddd void add(VkMenuItem *, int pos = -1); This function allows an arbitrary instance of a VkMenuItem subclass to be added to a menu. This function is intended primarily to support new derived classes not currently supported by the ViewKit. aaaaddddddddSSSSuuuubbbbmmmmeeeennnnuuuu VkSubMenu *addSubmenu(VkSubMenu *submenu, int pos = -1); VkSubMenu *addSubmenu(const char *name, int pos = -1); VkSubMenu *addSubmenu(const char *name, VkMenuDesc*, XtPointer defaultClientData = NULL); Installs a VkSubMenu object into a menu. The first form adds an existing VkSubMenu instance. The second form creates and returns an instance containing no items, while the third form creates a VkSubMenu from the given static menu description. aaaaddddddddRRRRaaaaddddiiiiooooSSSSuuuubbbbmmmmeeeennnnuuuu VkRadioSubMenu *addRadioSubmenu(VkRadioSubMenu *submenu, int pos = -1); VkRadioSubMenu *addRadioSubmenu(const char *name, int pos = -1); VkRadioSubMenu *addRadioSubmenu(const char *name, VkMenuDesc*, XtPointer defaultClientData = NULL); These functions have the same behavior as _a_d_d_S_u_b_M_e_n_u(), except that the new submenu pane is configured as a radio box. bbbbuuuuiiiilllldddd(((()))) void build(Widget parent); It is possible to need a menu item to exist, but to not want it to be visible on the screen. For example, an application might start up with some menu panes hidden from view, to appear when the application's state changes. To display a menu hierarchy without forcing _a_l_l items to become visible, call _b_u_i_l_d(), with a parent PPPPaaaaggggeeee 9999 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) widget. ffffiiiinnnnddddNNNNaaaammmmeeeeddddIIIItttteeeemmmm VkMenuItem *findNamedItem(const char *name, Boolean caseless = FALSE); Finds and returns a menu item of the specified name starting at the point in the menu hierarchy represented by the object for which this function is called. If caseless is TRUE, the search is case- insensitive. If no object with the given name is found, the function returns NULL. If multiple instances of the same name exist, the function returns the first name found in a depth-first search. Note that it may be necessary to cast the return value if a specific type of item is needed. For example: VkMenuToggle * toggle; toggle = (VkMenuToggle*) pane->findNamedItem("toggle1"); rrrreeeemmmmoooovvvveeeeIIIItttteeeemmmm VkMenuItem *removeItem(const char *name); Removes the named item from this menu. The removed item is returned. This is functionally equivalent to: (menu->findNamedItem(name))->remove(); aaaaccccttttiiiivvvvaaaatttteeeeIIIItttteeeemmmm VkMenuItem *activateItem(const char * ); Activates and returns the named item. This is functionally equivalent to: (menu->findNamedItem(name))->activate(); ddddeeeeaaaaccccttttiiiivvvvaaaatttteeeeIIIItttteeeemmmm VkMenuItem *deactivateItem(const char * ); Deactivates and returns the named item. This is functionally equivalent to: PPPPaaaaggggeeee 11110000 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) (menu->findNamedItem(name))->deactivate(); rrrreeeeppppllllaaaacccceeee VkMenuItem *replace(const char *name , VkMenuItem * newItem); Replace the named item with the specified item. This function returns the replaced item. mmmmeeeennnnuuuuTTTTyyyyppppeeee virtual VkMenuItemType menuType() = 0; Identifies the type of a VkMenu subclass. Possible types are BAR, POPUP, SUBMENU, OPTION. ccccllllaaaassssssssNNNNaaaammmmeeee virtual const char* className(); This function returns 'VkMenu" for this class. iiiissssCCCCoooonnnnttttaaaaiiiinnnneeeerrrr Boolean isContainer(); This function returns TRUE for VkMenu and all derived classes ggggeeeettttSSSSccccrrrreeeeeeeennnn ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy VkScreen *getScreen(); Return the VkScreen object associated with this menu. ggggeeeettttIIIItttteeeemmmmPPPPoooossssiiiittttiiiioooonnnn int getItemPosition(VkMenuItem*); int getItemPosition(char *name); int getItemPosition(Widget); Returns the position of a given menu item within this menu. ooooppppeeeerrrraaaattttoooorrrr[[[[]]]] VkMenuItem * operator[] (int index) const; Returns the indexed child of a menu. nnnnuuuummmmIIIItttteeeemmmmssss PPPPaaaaggggeeee 11111111 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) int numItems() const; Returns the number of items currently in a menu. uuuusssseeeeOOOOvvvveeeerrrrllllaaaayyyyMMMMeeeennnnuuuussss static void useOverlayMenus(const Boolean flag); See _M_E_N_U_S _I_N _T_H_E _O_V_E_R_L_A_Y _P_L_A_N_E_S in VkSubMenu(3). Puts all menus in the overlay planes. uuuusssseeeeWWWWoooorrrrkkkkPPPPrrrrooooccccssss static void useWorkProcs(Boolean flag); If TRUE (the default value), application startup time is improved because menus are built using a workproc. An application might wish to turn this off if there is a conflict with its own workproc usage. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkMMMMeeeennnnuuuuIIIItttteeeemmmm show(), hide(), manageAll(), setLabel(), setPosition(), activate(), deactivate(), remove(), show(), _position, _isBuilt, _sensitive, _parentMenu, _label, _isHidden, _unmanagedWidgets, _numUnmanagedWidgets, IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCoooommmmppppoooonnnneeeennnntttt installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(), setDefaultResources(), getResources(), manage(), unmanage(), baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCaaaallllllllbbbbaaaacccckkkkOOOObbbbjjjjeeeecccctttt callCallbacks(), addCallback(), removeCallback(), removeAllCallbacks() KKKKNNNNOOOOWWWWNNNN DDDDEEEERRRRIIIIVVVVEEEEDDDD CCCCLLLLAAAASSSSSSSSEEEESSSS VkOptionMenu, VkSubMenu, VkHelpPane, VkRadioSubMenu, VkMenuBar, VkPopupMenu, CCCCLLLLAAAASSSSSSSSEEEESSSS UUUUSSSSEEEEDDDD BBBBYYYY TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS VkMenuAction, VkMenuActionWidget, VkMenuConfirmFirstAction, VkMenuItem, VkMenuLabel, VkMenuSeparator, VkMenuToggle, VkRadioSubMenu, VkSubMenu PPPPaaaaggggeeee 11112222 VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) VVVVkkkkMMMMeeeennnnuuuu((((3333xxxx)))) KNOWN CLASSES THAT USE THIS CLASS VkAlignmentGroup, VkGraph, VkHelpPane, VkMenu, VkMenuBar, VkMenuItem, VkWindow SSSSEEEEEEEE AAAALLLLSSSSOOOO VkMenuItem, VkComponent, VkAlignmentGroup, VkGraph, VkHelpPane, VkMenuAction, VkMenuActionWidget, VkMenuBar, VkMenuConfirmFirstAction, VkMenuItem, VkMenuLabel, VkMenuSeparator, VkMenuToggle, VkRadioSubMenu, VkSubMenu, VkWindow _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Sheifler and Jim Gettys _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF PPPPaaaaggggeeee 11113333